BZRto
*****

BZRto translates an outline font that's in our home-grown BZR outline font format (described below) to some other form: Metafont, Type 1 PostScript, Type 3 PostScript, or BPL.

BPL format is simply a human-readable form of BZR files.  See BPL files.  We discuss the other output forms below.

Besides straight format conversion, BZRto can also:

  * merge fonts, possibly of different sizes (see the -concat option in Invoking BZRto);

  * slant fonts, so the oblique version of a font can be made without respecifying the character shapes (see the -oblique-angle option);

  * create new characters by combining existing ones, via a fairly general command language (see CCC files).

Metafont and BZRto
==================

Metafont is a language for specifying graphic shapes, particularly characters in a font of a type, as well as the name of the program which interprets the language.  It is commonly used to generate fonts for TeX and related software (TeX and Metafont were developed more-or-less simultaneously by Donald Knuth during the years 1977--1985).  See Archives, for how to obtain the Metafont program.

BZRto generates a Metafont font FOO.mf from the input file FOO10.bzr (the 10 being the design size of the input) if you specify the -metafont option, as in:

     bzrto -metafont FOO

Presuming Metafont has been installed properly at your site, you can then make both a TFM and a GF file for FOO at a size of 10pt and rasterized for your most common output device with the command:

     mf '\mode:=localfont; input FOO'

(The single quotes are not seen by Metafont; they just protect the backslash and semicolon from interpretation by your shell.)

The assignment to mode tells Metafont the name of your output device.  localfont should be a synonym for some real output device, defined when Metafont was installed.  The GF file will be named FOO.DPIgf, where DPI is the resolution of the localfont device.

Given the TFM and GF file, you can now use the font in TeX.

Metafont output at any size
---------------------------

We described above how to get Metafont output at a size of 10pt. To generate a GF file for a font FOO at a different size, assign to designsize on the command line, as follows:

     mf '\mode:=localfont; designsize:=INTEGER; input FOO

For example, if localfont corresponds to a 300dpi device, and you specify designsize:=6, this command creates FOO.180gf, i.e., a 40% reduction from FOO.300gf.

In some cases, it may be more convenient to specify a magnification factor than a new point size.  (For example, this is the case if you are enlarging or reducing an entire document by some constant factor, as with TeX's \magnification command.)  You can do this by assigning to mag:

     mf '\mode:=localfont; mag:=REAL; input FOO

By default, mag is 1.0.  You can also assign to both mag and designsize.  For example, if you set designsize to 5 and mag to 4, the output will be a 20pt font.

Although the Metafont language allows nonlinear scaling of fonts, so that the 6pt font would not simply be a reduced version of the 10pt font, BZRto cannot take advantage of this sophistication. The reason is that BZR files specify a single set of outlines, and the nonlinear scaling cannot be deduced from that.  Perhaps we will extend the programs someday to handle interpolation between outlines of different sizes.

Proofing with Metafont
----------------------

While creating fonts, it is useful to enlarge the character shapes enough to be able to make out small details.  This blowing-up process is called proofing.  Metafont works together with GFtoDVI, another program created as part of the TeX project, to do this.

You can make two kinds of proofs with Metafont: gray proofs and smoke proofs.  Metafont calls the former proof mode, and the latter smoke mode.  proof mode is the default, so if you do not assign to mode at all, you get gray proofs.  To get smoke proofs for a font FOO, you run Metafont as follows:

     mf '\mode:=smoke; input FOO'

(See the preceding sections for general information on running Metafont.)  In proof or smoke mode, by default Metafont will display the characters online as it runs (if you are on a terminal capable of this, e.g., running under X).  If you aren't interested in seeing this online output, you can say nodisplays; on the command line.

In both kinds of proofs, the font is produced at a very high resolution, typically thousands of pixels per inch, to minimize (or eliminate) distortion due to rasterization difficulties.  To be more precise, the resolution is chosen so that the designsize of the font fills proof_size inches; by default, proof_size is 7, which works well enough for both letter-size and A4 paper.

In order to calculate this, Metafont must also know the resolution of the final output device.  This is called proof_resolution, and is 300 by default.

You can change the values of proof_size and proof_resolution on the command line; the actual calculation is done in bzrsetup.mf.

After running Metafont, you will have a GF file, e.g., FOO.2602gf.  You can then make a DVI file you can preview or print with:

     gftodvi FOO.2602gf

This creates FOO.dvi.  In the DVI output from GFtoDVI, each character in the font has its own page.  Some additional information is also present, as follows:

In proof mode, the character shapes are printed in a ``gray'' font, and the starting and ending points of each spline (or line) in the character outline are shown.  (Thus, you can see if Limn did a good job choosing those points.)  If you set proofing > 2, the control points for each spline will also be shown.  If a point would otherwise overlap with others on the output, an equation is put off to the right defining where it appears.

In smoke mode, the character shapes are printed in black; if you put the output on the wall and stand back, you can get an idea of how the font is coming along.  The character is also shown at its true size off to the right (assuming you have made the font at the true-size resolution, of course).

You may find that the extra information to the right of the character (``overflow equations'' in proof mode; the true-size character in smoke mode) is being lost off the edge of the page.  You can change where GFtoDVI puts this with the -overflow-label-offset option to GFtoDVI.

See the Metafontbook and the GFtoDVI documentation for more details.

Type 1 PostScript fonts and BZRto
=================================

The Type 1 font format, invented by Adobe Systems, Inc., is the most common representation for PostScript fonts.  Adobe first published its specification in the book Adobe Type 1 Font Format in 1990.  It defines a limited set of operations; general PostScript programs cannot be represented as Type 1 fonts.  It also defines hints---ways of improving characters' appearances at low resolution and/or small small sizes---which cannot be represented in PostScript proper.

BZRto generates a Type 1 font FOO.gsf from the input file FOO10.bzr (the 10 being the design size of the input) if you specify the -pstype1 option, as in:

     bzrto -pstype1 FOO

The file FOO.gsf consists only of plain text (it's not really ``human-readable'', since Type 1 format requires encryption of the character outlines).

Although Type 1 format also allows for encryption of the entire font, this is not required, and BZRto does not do it.  Some deficient PostScript interpreters do not recognize unencrypted fonts; but Ghostscript, the GNU quasi-PostScript interpreter, has no trouble.  We do not know of any utilities for encrypting an unencrypted Type 1 font, but presumably such a program would not be hard to write.

Type 3 PostScript fonts and BZRto
=================================

Type 3 PostScript fonts are not defined in a singular format, as are Type 1 fonts (see the previous section).  Rather, they are general PostScript programs which happen to meet the PostScript language's (liberal) requirements for being a font.  They can therefore be used with any PostScript interpreter.

BZRto generates a Type 3 font FOO.pf3 from an input BZR file FOO.bzr if you specify the -pstype3 option, as in:

     bzrto -pstype3 FOO

We do not know of any conventional extension for Type 3 fonts; we made up pf3 to stand for ``PostScript font Type 3''.

The most important part of a Type 3 font is the BuildChar routine, which does the actual rendering from the character program. Unlike Type 1 fonts, whose BuildChar routine is built into the PostScript interpreter, each Type 3 font supplies its own BuildChar routine.

The Type 3 fonts output by BZRto use a BuildChar routine defined in a separate file bzrbuildch.PS (distributed in the bzr directory).  They use the PostScript run command to read that file; so if you want to download one to a printer (which naturally will not have access to the file on your computer), you must replace the run command with the contents of the file.  For PostScript interpreters which run on a host computer, such as Ghostscript, you have to install bzrbuildch.PS in a directory where it will be found, but you need not modify the fonts.

CCC files
=========

The CCC (composite character construction) language allows you to define new characters in terms of existing ones.  This is useful for building such characters as pre-accented A's (from a piece accent and an `A').

A CCC file consists of a sequence of character definitions, each of which looks like:

     define NAME = STATEMENTS end

where NAME is a character name, presumably from the encoding file specified with the -encoding option (see Invoking BZRto). See Character names, for the details of character names.

We describe the possible STATEMENTS below.

You may also include comments starting with a % character and continuing to the end of the line.

CCC setchar statements
----------------------

To use an existing character as part of a new character, you can use either the setchar or setcharbb statement.  They both take a character name in parentheses as their argument, as in:

     setchar ( NAME )
     setcharbb ( NAME )

See Character names, for the details of character names.

The difference between the two commands lies in their treatment of the existing character's sidebearings: the setchar command includes them, and setcharbb does not.  setcharbb also removes any white space above and below the character shapes, as is usually present in accent characters.

This difference lets you construct characters without worrying about interaction between their side bearings.  For example, you could make an `A' with an acute accent centered over the body of the `A' as follows:

     define Aacute =
       setchar (A)
       hmove -.5 width (A)
       vmove height (A)
       setcharbb (acute)
     end

(See the next section for a description of the hmove and vmove commands.)  Without the setcharbb command, this definition would be complicated by the side bearings on the acute character.

CCC move statements
-------------------

To change the current position in a CCC file, you can use the hmove or vmove command; as you might expect, the former moves horizontally and the latter vertically.

Both take a single argument: a dimension, which is an optional real number followed by a unit of measure.  The real number is a multiplying factor.  For example, one of the units is pt (signifying printer's points, as usual), so the command hmove 3pt moves three points to the right (a pretty small distance).

Here are the possible units of measure:

bbheight ( NAME )
     The height exclusive of blank space above or below the shape of the character NAME if it exists.

bbwidth ( NAME )
     The width exclusive of side bearings of the character NAME if it exists.

capheight
     The height of the capital letters, e.g., H.  See xheight for how this is determined.

depth ( NAME )
     The depth of the character NAME.

designsize
     The design size of the main input BZR font.

em
     The quad width of the font.  This value is determined analogously to xheight, below.

fontdepth
     The maximum depth any character in the font descends below the baseline. Again, this is determined analogously to xheight.

height ( NAME )
     The height of the character NAME.

pt
     Printer's points; 72.27pt = 1in.  Since dimensions specified in points are absolute distances, they do not scale when the font size changes.

width ( NAME )
     The set width of the character NAME.

xheight
     The x-height of the main input font.  If a TFM file corresponding to the main BZR file exists and defines this, that value is used; otherwise, the height of a suitable character (e.g., x) is used if one exists; otherwise, it's zero.  BZRto treats the other font-related units of measure in the same way.

If the character NAME does not exist, an error is given, and the command ignored.

Invoking BZRto
==============

This section describes the options that BZRto accepts. See Command-line options, for general option syntax.

The root of the main input fontname is called FONT-NAME below.

-concat BZR-NAME1, BZR-NAME2, ...
     Concatenate the main input file with the given BZR-NAMEs; if a character code exists in more than one of the BZR files, it's the first occurrence that counts.  The BZR files can have any design size; the output is normalized to the size of the main input file.

-ccc-file FILENAME
     Read the CCC file FILENAME (if FILENAME has a suffix) or FILENAME.ccc (if it doesn't).  Default is to use FONT-NAME for FILENAME, but if BZRto does not find the file FONT-NAME.ccc, it does not complain.

-encoding FILENAME
     Specify the encoding file for the input font, so character names in the CCC files can be matched to character codes.  If FILENAME has no suffix, use FILENAME.enc, otherwise just FILENAME. The default is to guess the encoding from the codingscheme string in a TFM file corresponding to the main input file, if such exists.

-help
     Print a usage message.  See Common options.

-metafont
     Translate the input to a Metafont program; write to FONT-NAME.mf.  See Metafont and BZRto.

-mf
     Synonym for -metafont.

-oblique-angle ANGLE-IN-DEGREES
     Angle in degrees from the vertical by which to slant the shapes; default is zero.

-output-file FILENAME
     Output to FILENAME (if it has a suffix) or to FILENAME.FONT-FORMAT (if it doesn't), where FONT-FORMAT is mf, gsf, etc.  If you give more than one of the output format options (i.e., metafont, pstype1 and pstype3), FILENAME cannot have a suffix.  The default is FONT-NAME with a trailing number removed, so that, for example, an input filename of cmr10 becomes cmr.

-ps-font-info NAME1:VALUE1,...
     Assign each VALUE to the corresponding NAME when outputting a PostScript font (either Type 1 or Type 3).  Case is significant in both the NAMEs and VALUEs.  You can specify the following:

     FontName:STRING
          The full PostScript name of the font; e.g., Times-BoldItalic. The default is unknown.

     FamilyName:STRING
          The name of the typeface family to which this font belongs; e.g., Times.  The default is to use FontName up to the first -.

     Weight:STRING
          The typographic weight of the font, e.g., Bold.  If FontName contains one of the strings Black, Book, Bold, Demi, ExtraBold, Light, Heavy, Regular, Semibold, or Ultra, that is the weight.  Otherwise, BZRto uses Medium.

     ItalicAngle:REAL
          The angle in degrees by which the font slopes to the right from the vertical.  Default is zero.  Typical slanted or italic fonts have values between 10--20.

     isFixedPitch:true or false
          Whether or not this font is monospaced.  If a TFM file corresponding to the main BZR file exists, and specifies a zero interword stretch and shrink, and a nonzero interword space, the default is true. Otherwise, it's false.

     UnderlinePosition:REAL
          Distance from the baseline for positioning underlines, in units of the character coordinate system.  Default is -100.

     UnderlineThickness:REAL
          Thickness of underlines.  Default is 50.

     UniqueID:NON-NEGATIVE INTEGER
          An integer in the range 0 to 16777215 (2^24 - 1) uniquely identifying this font.  The default is zero, meaning (for our purposes) not to output any UniqueID.  This avoids unlikely-but-possible conflicts with existing fonts.

     version:STRING
          Identification for the particular version of this font.  If a TFM file corresponding to the main BZR file exists, and specifies a version number, that is the default; otherwise, there is none.

     All values except FontName and UniqueID go in the FontInfo dictionary.

-pstype1
     Translate the input to (unencrypted) PostScript Type 1 font format; write to FONT-NAME.gsf.  See Type 1 and BZRto.

-pstype3
     Translate the input to PostScript Type 3 font format; write to FONT-NAME.pf3.  See Type 3 and BZRto.

-range CHAR1-CHAR2
     Only process characters between the character codes CHAR1 and CHAR2, inclusive.

-text
     Translate the font to a BPL file, i.e., human-readable text; write to standard output.  See BPL files.

-verbose
     Output progress reports to standard output, unless -text is specified, in which case output to standard error.

-version
     Print the version number.

BZR files
=========

This section describes the technical definition of the BZR file format.  It is intended for programmers who wish to write other programs which read or write such files.  The present distribution includes a subroutine library which can be shared among programs (Limn, BPLtoBZR, and BZRto all use it); new programs can and probably should use the existing library as well.  The source code is in the bzr directory.

The BZR file format shares the philosophy of the TeX project file formats (DVI, GF, PK, etc.): machine-independence; compactness; and easy interpretation.

BZR files have three parts: a preamble, character definitions, and a postamble.  We describe each below, as well as some general considerations.

BZR format introduction
-----------------------

This section describes some general conventions of the BZR format.

In the following sections, we use the notation NAME[N] to mean that some constituent NAME of the BZR file takes up N bytes.  If NAME is all capital letters, it is an opcode, i.e., a command byte, and therefore we give no [N] after NAME, since all opcodes are a single byte.  The numerical value of each opcode is given in the source file bzr/bzr_opcodes.h.

Some values in BZR files are ``pointers''.  These values give the location of some other byte in the file.  The first byte is numbered 0, the next byte numbered 1, and so on.

Besides commands which actually define the font, the BZR format has a NO_OP command, which does nothing.  Any number of NO_OP's can occur between the preamble and the character definitions, between character definitions and commands within characters, between the character definitions and the postamble, and after the postamble.  But they may not occur within the preamble, the postamble, or between a command and its parameters.

Besides simple integers, BZR format uses a fixed-point representation of real numbers called a scaled, which is three bytes: two bytes of fraction and one byte of integer.  We can get away with such a small range because almost all numbers are scaled by the design size; i.e., in a 10-point font, a designsize-scaled value of 1.0 would represent 10 points (quite a large distance, relatively speaking).

In fact, designsize-scaled numbers are typically less than 1.0, so the BZR format provides for abbreviating such, thus making the font smaller, as detailed in the following sections.

Negative numbers are represented in 2's complement notation, and multibyte values are stored in BigEndian order, regardless of the conventions of the host computer.  This makes a BZR font file portable between different architectures.

BZR preamble
------------

The preamble of a BZR file has two components, the font's design size and a comment: designsize[3], k[1], comment[k].

See BZR format introduction, for general information about BZR files and for the definition of the types used here.

The designsize is a scaled number in printer's points.

The K-byte long comment typically identifies the source and creation date of the BZR file.

BZR characters
--------------

BZR characters consist of an identifying command, metric information, shape information, and a terminating EOC command.

We describe these parts below.

BZR character beginnings
........................

BZR format provides two ways to start characters: an abbreviated one, which saves space in common cases, and a longer form which (we hope) will always suffice.

The short form looks like this:

     BOC_ABBREV BOC_ABBREV
     charcode[1]
     set-width[2]
     llx[2] lly[2] urx[2] ury[2]

The long form:

     BOC BOC
     charcode[1]
     set-width[3]
     llx[3] lly[3] urx[3] ury[3]

Here is a description of these components:

  * The BOC or BOC_ABBREV opcode byte introduces the character.

  * charcode defines the character code in question.

  * set-width defines the set width of the character, given as a design-size scaled, in printer's points.

  * llx ... ury (which stand for ``lower left x'', ``lower left y'', ``upper right x'', and ``upper right y'') define the bounding box for this character.  The values are designsize-scaled, in printer's points.  The bounding box is not guaranteed to be the tightest possible, because it is difficult to compute the exact path of any splines in the character shape (see BZR character shapes).

As with other formats, the left side bearing is defined by llx, and the right side bearing by set-width - urx.

See BZR format introduction, for general information about BZR files and for the definition of the types used here.

BZR character shapes
....................

In the BZR format, a character shape is defined as a sequence of (non-contiguous) closed paths, i.e., outlines.  Each path can contain straight lines and Bezier cubic splines.  As a BZR-reading program interprets the character definition, it keeps track of a ``current point'', which is initially undefined.

Each path---and therefore also the character shape itself---starts with a path command: PATH, x[3], y[3].  This finishes off any previous outline and starts a new one, setting the current point to (x,y).  x and y are designsize-scaled values in printer's points.

After a path command has started an outline, a sequence of zero or more line and/or spline commands, intermixed in any order, follows.  (A path command followed by another path command is allowed, but does nothing useful.)

Although the BZR format itself does not require it, for the font to work properly when translated to some other formats, the ``outside curves'' must be drawn counterclockwise, and the inside ones clockwise.

The BZR format defines both abbreviated and long versions of both straight line and spline commands, as follows.

The abbreviated line command is:

     LINE_ABBREV LINE_ABBREV opcode in BZR files
     ex[2]
     ey[2]

which defines a straight line from the current point to (ex,ey).  ex and ey are designsize-scaled numbers in points.  After drawing the line, the current point is set to (ex,ey).

The long form of the line command differs only in starting with a LINE opcode, and the coordinate parameters being three bytes long, instead of two.

The spline commands are analogous.  Here is the abbreviated form:

     SPLINE_ABBREV SPLINE_ABBREV opcode in BZR files
     c1x[2] c1y[2]
     c2x[2] c2y[2]
     ex[2] ey[2]

This defines a Bezier spline with initial point the current point, control points (c1x,c1y) and (c2x,c2y), and ending point (ex,ey).  The current point is then set to (ex,ey).  As with the line commands, the coordinate parameters are designsize-scaled in units of points.

Also as with the line commands, the long form of the spline command differs only in starting with a SPLINE opcode and the other parameters being three bytes long instead of two.

BZR postamble
-------------

The postamble of a BZR file consists of the following.  See BZR format introduction, for general information about BZR files and for the definition of the types used here.

     POST POST opcode in BZR files
     llx[3] lly[3] urx[3] ury[3]
     character locators (see below)
     POST_POST POST_POST opcode in BZR files
     nchars[1]
     post-ptr[4]
     id[1]
     1 to any number of NO_OP's

Here is a description of these components:

  * llx ... ury are all designsize-scaled numbers.  They define the bounding box for the entire font, which is simply the smallest box that encloses all the characters.  See BZR character beginnings.

  * A character locators provides a pointer to the first byte of the corresponding character description, i.e., its BOC.  There are two forms of character locators: one abbreviates the common case of the pointer being less than 65536; the other allows for a full four-byte pointer value.

     More precisely, an abbreviated character locator consists of:

          CHAR_LOC_ABBREV charcode[1] pointer[2]

     and a long character locator consists of:

          CHAR_LOC charcode[1] pointer[4]

  * nchars is the number of characters defined in the BZR file.

  * post-ptr points to the POST byte.

  * id identifies the version of BZR format; this is currently 75.

This way of ending BZR files makes it straightforward to process a BZR file from end to beginning, even though it must of course be written beginning to end.  The BZR-reading program can position itself at the end of the file, skip over the NO_OP bytes at the end to the id byte, and then read the pointer to the postamble proper, which provides enough information to read each character individually.  This eliminates the need to read the entire (potentially large) BZR file into memory before doing any processing.